OTStreamLogViewer is both a sample and a developer tool. As a sample, it shows how to use the OT raw streams API to communication with modules in the OT kernel. As a tool, it allows you to view the output of the STREAMS logging facility (strlog). This is extremely helpful when developing OT kernel plug-ins: modules drivers, and port scanners.
About STREAMS Logging
The STREAMS architecture defines a standard logging facility in the form of the strlog routine. This function is described in detail later, but for the moment it is suffice to say that strlog allows kernel code to create a log entry (in which the most important data is a text message) that is passed to the "log" device. A client-side process can connect to this device (by opening a raw stream) and receive these log entries as STREAMS messages.
Typically, on a UNIX STREAMS system, there is a client-side process that connects to the log device and writes these log messages to a system administration file. Under Open Transport, no such process is provided, although the entire logging infrastructure is present. OTStreamLogViewer performs the function of the client-side logging process with a cutesy Mac OS user interface.
The log events created by the strlog function are aimed at two audiences. Error events are typically an indication of some failure within the network protocol stack and are meant to be read by system adminstrators. Trace events are typically used for "writing to stdout" debugging by the authors of STREAMS protocol modules. OTStreamLogViewer allows you to selectively see either or both types of events.
The strlog Function
The prototype for strlog is defined in "strlog.h", one of the low-level interface files that comes with the Open Transport SDK.
The function result is not meaningful. The mid parameter is typically your module’s module ID number, as defined by you in the mi_idnum filed of module_info record referenced by your streamtab. The sid parameter is typically the minor device number of a stream connected to your module. The level parameter specifies the importance of the log message, as defined by the following constants (defined in "OpenTptModule.h"):
enum
{
kOTLvlFatal = 0,
kOTLvlNonfatal = 1,
kOTLvlExtFatal = 2,
kOTLvlExtNonfatal = 3,
kOTLvlUserErr = 4,
kOTLvlInfoErr = 5,
kOTLvlInfoOnly = 6
};
Note: These three parameters are uninterpreted by strlog, except insofar as it matches the parameters against the filter specified by the trace logging client. Specifically you can pass any value you want for mid and sid; they do not have to be valid module ID or stream minor number. In fact, you don’t even have to be developing a module to use strlog. You can call strlog from any kernel code.
The flags parameter specifies the type of log event to be created. The following bit masks are defined in "strlog.h":
#define SL_ERROR 0x4 /* Pass message to error logger */
#define SL_TRACE 0x8 /* Pass message to tracer */
#define SL_CONSOLE 0x10 /* Print the message on the console */
#define SL_FATAL 0x1 /* Fatal error */
#define SL_NOTIFY 0x2 /* Notify the system administrator */
#define SL_WARN 0x20 /* Warning */
#define SL_NOTE 0x40 /* Notice this message */
You can specify any combination of these flags by ORing the masks together. strlog ignores the flags except for SL_TRACE and SL_ERROR. These flags control whether the log event is sent to either the trace logger (typically used for debugging) or the error logger (typically used for system admin messages). In addition, the SL_CONSOLE flag allows you to specify that the message should be printed on the system console, but this has no effect under Open Transport.
Finally, the fmt (and any remaining parameters) are used in a printf-like fashion to form the message string associated with this log. The following format specifiers are permitted: %c, %d, %m (memory, in hex), %o, %x, %s, %u.
Open Transport also defines a logging macro, STRLOG, which acts like a function with the following prototype:
This macros is a convenience function for use specifically by modules. The macro extracts the module ID and stream ID from the supplied queue_t parameter.
Reading Log Events
The client-side interface to the "log" device is defined in "strlog.h". Rather than describe this in detail, I will refer you to the comments in "LogEngine.h" and "LogEngine.c". These files represent a standalone library which you can use to implement a STREAMS logging facility under Open Transport.
Packing List
The sample includes the following items:
• Read Me — OTStreamLogViewer — This document.
• OTStreamLogViewer.µ — A CodeWarrior project to build the OTStreamLogViewer.
• OTStreamLogViewer — A compiled version of the above.
• OTStreamLogViewer.rsrc — Resources for the above.
• StreamLogResources.h — C constants for all the resource IDs.
• OTStreamLogViewer.c — The bulk of the application code, including the main function.
• FileLogging.h, FileLogging.c — The code that implements logging to a file.
• LogEngine — A folder containing the log engine, a library that can be extracted from this program to provide client-side logging support in any application.
• IC Libraries — A bunch of source files, extracted from the Internet Config source, that provide generally useful extensions to the Mac OS toolbox. See the Read Me inside the folder for more information.
• Internet Config APIs — A minimal set of interfaces and libraries, extracted from the IC 2.0 SDK, that allow OTStreamLogViewer to store its state in the Internet Config preferences database. See the Read Me inside the folder for more information.
Building the Sample
To build the sample you will need:
• CodeWarrior Pro 2, with C and Pascal compilers installed.
• The Open Transport SDK. I used version 1.3 of the SDK, but newer and old versions (back to 1.1.1) should work OK.
• The ASLM 2.0 SDK, available on the Mac OS SDK CDs.
To build the sample, the first thing you have to do is grab all the OT interface files from the OT SDK and put them in one folder. The interfaces that come with CodeWarrior don’t include all the low-level APIs that you will need. Similarly, you should group all the OT libraries in the same folder. Then modify the access paths for the project to point those folders.
Next you should modify the access paths for the project to point to the ASLM developer tools folder.
The next step is to open the “OTStreamLogViewer.µ” project file, select the FAT target, and make the project. This results in a fat version of the application.
Coding Notes
There are three interesting points in the sample code:
• The OTStreamLogViewer application contains a lot of user interface code. Writing user interface code under Mac OS is much easier if you have a library of existing functions to wrap around the Mac OS to provide extra functionality. In this sample I use a library of code extract from the Internet Config source code. [Internet Config is in the public domain, so there’s no intellectual property problems with using it’s source.] The library code is actually written in Pascal, with C header files that allow you to call the Pascal code from C source.
• This sample demonstrates the use of a raw stream in asynchronous mode. The notifier in "LogEngine.c" shows how to efficiently raw STREAMS messages from the raw stream.
• This sample uses the OT memory allocation routines (OTAllocMem and OTFreeMem) for allocating buffers to store log entries in the above notifier (ie at 'interrupt time'). The OT memory allocation routines have a number of important attributes that you should be aware of. There’s a long discussion of this in "OTStreamLogViewer.c".
• The OT raw streams API is not available to emulated clients running on PowerPC-based computers. For this reason the application should always be compiled fat.
• The 68K version was a real pain to build. Firstly, you have to set CodeWarrior to use 4 byte integers, because the ASLM header files (specifically InitLibraryManager) assume 4 byte integers. *sigh* Secondly, you have to make sure that “LibraryManager.o” is linked last, ie comes last in the Segments tab in the project window. If you don’t do this, some ANSI C stuff in “LibraryManager.o” will override the standard stuff in the MSL library and bad things will result.
Using OTStreamLogViewer
Alas, user documentation has been deferred to a future release. Some hints and tips:
• Never attempt to run the 68K version on a PPC. See DTS Q&A NW 48 for details why not:
<http://devworld.apple.com/dev/qa/nw/nw48.html>
• If you want the PowerPC version to remember window positions, install Internet Config Extension 2.0 or later. For the 68K version, any version of Internet Config should suffice.
• If your kernel code calls strlog in a very bursty fashion, you may want to increase the partition size of the application. The application accepts log entries at interrupt time but can’t process them until SystemTask time. If it receives a large number (say 2000) log entries at interrupt time before it gets SystemTask time, the application will start dropping log entries.
• If you turn on file logging, OTStreamLogViewer will log to a text file call “OTStreamLogViewer Log” in the root of the boot volume. Yes, I know it’s lame user interface (–:
Credits and Version History
OTStreamLogViewer was written by Quinn “The Eskimo!” as Apple Developer Technical Support sample code. If you find any problems with this sample, mail <DTS@apple.com> with “Attn: Quinn” as the first line of your mail and I’ll try to fix them up.
Version 1.0b1 (Mar 1998) is the first release version.
Version 1.0b2 (Jul 1998) fixes a slight memory leak. Important safety tip: always remove a notifier from a raw stream before closing the stream. Updated to CodeWarrior Pro 2. Updated to IC 2.0 final stuff.
